Skip to main content

Audit Log API

The Audit Log API endpoint provides access to dataflow audit logs, allowing you to track administrative changes to categories, datasets, and policies within the Cyberhaven platform.

Endpoint​

POST /api/rest/v1/audit-log/dataflow/list

Request Format​

Basic Request​

curl -H 'content-type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  https://$DEPLOYMENT/api/rest/v1/audit-log/dataflow/list \
  -k --data '{}'

Request with Filters​

curl -H 'content-type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  https://$DEPLOYMENT/api/rest/v1/audit-log/dataflow/list \
  -k --data '{
    "filters": {
      "types": ["created_category", "edited_dataset"],
      "users": ["admin@company.com"],
      "include_cyberhaven": false
    },
    "page_size": 50
  }'

Request Parameters​

Filter Parameters​

ParameterTypeDescription
category_idstringFilter by specific category ID
dataset_idstringFilter by specific dataset ID
include_cyberhavenbooleanInclude system-generated events
typesarray[string]Filter by event types
usersarray[string]Filter by user emails

Pagination Parameters​

ParameterTypeDescription
page_idstringToken for next page
page_sizeintegerNumber of results per page (max 1000, default 50)

Event Types​

Category Events​

TypeDescription
created_categoryNew category created
deleted_categoryCategory deleted
edited_categoryCategory properties modified
renamed_categoryCategory name changed
edited_policy_for_categoryCategory policy rules updated

Dataset Events​

TypeDescription
created_datasetNew dataset created
deleted_datasetDataset deleted
edited_datasetDataset properties modified
renamed_datasetDataset name changed
edited_policy_for_datasetDataset policy rules updated

System Events​

TypeDescription
noneNo specific event type

Response Format​

Response Structure​

{
  "events": [
    {
      "time": "2024-01-15T10:30:00Z",
      "type": "created_category",
      "user": {
        "id": "user-123",
        "name": "John Doe",
        "email": "john.doe@company.com"
      },
      "data": {
        "category": {
          "id": "cat-456",
          "name": "Financial Data",
          "description": "Financial information protection",
          "severity": 3,
          "dataset_ids": ["ds-789", "ds-101"]
        }
      },
      "prev": null
    },
    {
      "time": "2024-01-15T11:15:00Z",
      "type": "edited_dataset",
      "user": {
        "id": "user-124",
        "name": "Jane Smith",
        "email": "jane.smith@company.com"
      },
      "data": {
        "dataset": {
          "id": "ds-789",
          "name": "Credit Card Numbers - Updated",
          "description": "Updated credit card detection rules",
          "sensitivity": 4
        }
      },
      "prev": {
        "dataset": {
          "id": "ds-789",
          "name": "Credit Card Numbers",
          "description": "Credit card detection rules",
          "sensitivity": 3
        }
      }
    }
  ],
  "total": 250,
  "next_page_id": "eyJwYWdlIjoyLCJzaXplIjo1MH0="
}

Response Fields​

FieldTypeDescription
eventsarray[AdminEvent]Array of audit log events
totalintegerTotal number of matching events
next_page_idstringToken for next page (if available)

AdminEvent Object Fields​

FieldTypeDescription
timestringWhen the event occurred (ISO 8601)
typestringType of administrative event
userobjectUser who performed the action
dataobjectCurrent state after the change
prevobjectPrevious state before the change (if applicable)

User Object Fields​

FieldTypeDescription
idstringUnique user identifier
namestringUser's display name
emailstringUser's email address

Data/Prev Object Fields​

The data and prev objects contain either a category or dataset object depending on the event type:

Category Object​

FieldTypeDescription
idstringCategory identifier
namestringCategory name
descriptionstringCategory description
severityintegerSeverity level (0-4)
dataset_idsarray[string]Associated dataset IDs

Dataset Object​

FieldTypeDescription
idstringDataset identifier
namestringDataset name
descriptionstringDataset description
sensitivityintegerSensitivity level

Example Requests​

Get All Recent Events​

{
  "page_size": 100
}

Get Category Creation Events​

{
  "filters": {
    "types": ["created_category"]
  },
  "page_size": 50
}

Get Events for Specific User​

{
  "filters": {
    "users": ["admin@company.com"],
    "include_cyberhaven": false
  }
}

Get Events for Specific Category​

{
  "filters": {
    "category_id": "cat-456",
    "types": ["created_category", "edited_category", "deleted_category"]
  }
}

Get Dataset Modification Events​

{
  "filters": {
    "types": ["created_dataset", "edited_dataset", "renamed_dataset"],
    "include_cyberhaven": false
  }
}

Filtering Options​

Include System Events​

By default, events generated by the Cyberhaven system are excluded. To include them:

{
  "filters": {
    "include_cyberhaven": true
  }
}

Filter by Multiple Event Types​

{
  "filters": {
    "types": [
      "created_category",
      "edited_category", 
      "created_dataset",
      "edited_dataset"
    ]
  }
}

Filter by Multiple Users​

{
  "filters": {
    "users": [
      "admin1@company.com",
      "admin2@company.com",
      "security-team@company.com"
    ]
  }
}

Error Responses​

Common Error Codes​

CodeDescriptionSolution
400Invalid filter parametersCheck filter values and types
401Authentication failedVerify access token
403Insufficient permissionsContact administrator
500Internal server errorContact support

Error Response Format​

{
  "error": {
    "code": "INVALID_EVENT_TYPE",
    "message": "Invalid event type provided",
    "details": {
      "field": "types",
      "value": "invalid_type"
    }
  }
}

Integration Examples​

Python Example​

import requests
import json
from datetime import datetime, timedelta

def get_audit_logs(token, deployment, filters=None):
    url = f"https://{deployment}/api/rest/v1/audit-log/dataflow/list"
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {token}'
    }
    
    payload = {}
    if filters:
        payload['filters'] = filters
    
    response = requests.post(url, headers=headers, json=payload, verify=False)
    return response.json()

# Get recent category changes
filters = {
    "types": ["created_category", "edited_category", "deleted_category"],
    "include_cyberhaven": False
}

events = get_audit_logs(token, deployment, filters)
print(f"Found {events['total']} audit events")

for event in events['events']:
    print(f"{event['time']}: {event['type']} by {event['user']['email']}")

PowerShell Example​

$headers = @{
    'Content-Type' = 'application/json'
    'Authorization' = "Bearer $token"
}

$body = @{
    filters = @{
        types = @("created_category", "edited_dataset")
        include_cyberhaven = $false
    }
    page_size = 50
} | ConvertTo-Json -Depth 3

$response = Invoke-RestMethod -Uri "https://$deployment/api/rest/v1/audit-log/dataflow/list" `
    -Method Post -Headers $headers -Body $body

Write-Output "Found $($response.total) audit events"

foreach ($event in $response.events) {
    Write-Output "$($event.time): $($event.type) by $($event.user.email)"
}

Bash Example​

#!/bin/bash

# Get audit logs for specific user
curl -H 'content-type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  https://$DEPLOYMENT/api/rest/v1/audit-log/dataflow/list \
  -k --data '{
    "filters": {
      "users": ["admin@company.com"],
      "types": ["created_category", "edited_category"]
    },
    "page_size": 25
  }' | jq '.events[] | "\(.time): \(.type) by \(.user.email)"'

Use Cases​

Compliance Auditing​

Track all administrative changes for compliance reporting:

{
  "filters": {
    "include_cyberhaven": false
  },
  "page_size": 1000
}

Change Management​

Monitor specific category or dataset modifications:

{
  "filters": {
    "category_id": "critical-data-category",
    "types": ["edited_category", "edited_policy_for_category"]
  }
}

User Activity Monitoring​

Track actions by specific administrators:

{
  "filters": {
    "users": ["security-admin@company.com"],
    "include_cyberhaven": false
  }
}

Policy Change Tracking​

Monitor policy rule modifications:

{
  "filters": {
    "types": ["edited_policy_for_category", "edited_policy_for_dataset"]
  }
}

Best Practices​

  1. Filter by Event Type: Use specific event types to reduce response size
  2. Exclude System Events: Set include_cyberhaven: false for user-initiated changes only
  3. Implement Pagination: Use page_size and next_page_id for large result sets
  4. Monitor Critical Changes: Focus on policy and configuration modifications
  5. Regular Auditing: Periodically review audit logs for compliance